5 DATA FILE HANDLING 


You can use OPL to create data files (databases) like those used by the Data application. 
You can store any kind of information in a data file, and retrieve it for display, editing or 
calculations. 


This chapter covers: 

Creating data files 

Adding and editing records 
Searching records 


Using a data file both in OPL and in the Data application 


The Series 5 and the Series 3c database models differ quite substantially. However, the 
Series 3c method of database programming (except for some removed keywords as 
indicated) is completely understood by the Series 5 model and any existing code will not 
have to change. However, it is very strongly recommended that, on the Series 5 you use 
the new keywords INSERT, MODIFY, PUT and CANCEL, along with bookmarks and 
transactions, rather than using APPEND, UPDATE, POS and POSITION. 


If you are using the Series 5, it is recommended that you should read this chapter for a 
description of simple database use, and then the following chapter which refers 
specifically to features available on the Series 5. 
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FILEs, RECORDS AND FIELDS 


Data files (or databases) are made up of records which contain data in each of their fields. For 
example, in a database of names and addresses, each record might have a name field, a telephone 
number field, and separate fields for each line of the address. 


In OPL you can: 


e Create a new file with CREATE, or open an existing file with OPEN, and copy, delete and 
rename files with COPY, DELETE and RENAME. 


e Add anew record with APPEND, change an existing one with UPDATE, and remove a record 
with ERASE. 


e Fill in a field by assigning a value to a field variable. 


CREATING A DATA FILE 
Use the CREATE command like this: 








CREATE filename$,logical name, fieldl,field2,... 


For example: 











CREATE “clients”,B,nm$,tel$,ad1$,ad2$,ad3$ 





creates a data file called clients. 


The file name is a string, so remember to put quote marks around it. You can also assign the name 
string to a string variable (for example fi1$=“clients”) and then use the variable name as the 
argument - CREATE fi1$,A,fieldl, fieldz2. 














Logical names 


I You can have up to 26 data files open at a time. Each of these must have a logical name: A to Z. 


X 
I You can have up to 4 data files open at a time. Each of these must have a logical name: A, B, C or 
Dz. 


The logical name lets you refer to this file without having to keep using the full file name. 


A different logical name must be used for each data file opened - e.g. one called A, one called B and 
one called Cc. A file does not have to be opened with the same logical name as the last time it was 
opened. When a file is closed, its logical name is freed for use by another file. 


Fields 


fieldl, field2,... are the field names - up to 32 in any record. These are like variables, so - use % & 
or $ to make the appropriate types of fields for your data. You cannot use arrays. Do not specify the 
maximum length of strings that the string fields can handle. The length is automatically set at 255 
characters. 


Field names may be up to 8 characters long, including any qualifier like &. 


When referring to fields, add the logical file name to the front of the field name, to specify which 
opened file the fields belong to. Separate the two by a dot. For example, A. nameS is the name$ field 
of the file with logical name A, and C. age% is the age% field of the file with logical name C. 


The values of all the fields are 0 or null to start with. You can see this if you run this example program: 
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PROC creatfil: 





CREATE “example”,A,int%,long&,float,str$ 











RINT “integer=";a.int% 
RINT “long=";a.longé& 


RINT ‘“float=";a.float 











P 
P 
P 
PRINT “string=";a.strs$ 
Cc 
G 





OPENING A FILE 


When you first CREATE a data file it is automatically open, but it closes again when the program ends. 
If a file already exists, trying to CREATE it again will give an error - so if you ran the procedure 
creatfil: asecond time you would get an error. To open an existing file, use the OPEN command. 


OPEN works in the same way as the CREATE command. For example: 
OPEN “clients”,B,nm$,tel$,ad1$,ad2$,ad3$ 





e You must use the same filename as when you first created it. 


e You must include in the OPEN command each of the fields you intend to alter or read. You can 
omit fields from the end of the list; you cannot miss one out from the middle of the list, for 
example nm$, , ad1$ would generate an error, whereas nm$, te1$,ad1$ would be fine. 
They must remain the same type of field, but you can change their names. So a file created with 
fields name$, age% could later be opened with the fields a$, x. 


e You must give the file a logical name. See ‘Logical names’ above. You can’t have two files open 
simultaneously with the same logical name, so when opening the files, remember which logical 
names you have already used. 


You might make a new module, and type these two procedures into it: 


PROC openfile: 





IF NOT EXIST (“example”) 





CREATE “example”,A,int%,1lng&,fp,strs$ 














ELSE 








OPEN “example”,A,int%,1ng&,fp,strs 
ENDIF 
PRINT “Current values:” 


show: 





PRINT “Assigning values” 


A.int%=1 





A.lng&=&2**20 REM the lst & avoids integer overflow 
A. fp=SIN(PI/6) 

PRINT “Give a value for the string:” 

INPUT A.str$ 

PRINT “New values:” 


show: 
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RINT “integer=";A.int% 
RINT “long=";A.1lng& 
RINT “float=";A.fp 


RINT “string=";A.strs 








Opening/creating the file 


The IF...ENDIF checks to see if the file already exists, using the EXIST function. If it does, the file is 
opened; if it doesn’t, the file is created. 


Giving values to the fields 

The fields can be assigned values just like variables. The field name must be used with the logical file 
name like this: A. f£%=1 or INPUT A.fS. 

If you try to give the wrong type of value to a field (for example “Davis” to £%) an error message will 
be displayed. 


You can access the fields from other procedures, just like global variables. Here the called procedure 
show: displays the values of the fields. 


Field names 


You must know the type of each field, and you must give each a separate name - you cannot refer to the 
fields in any indexed way, e.g. as an array. 


Opening a file for sharing 


The OPENR command works in exactly the same way as OPEN, except that the file cannot be written 
to (with UPDATE or APPEND), only read. However, more than one running program can then look at 
the file at the same time. 


SAVING RECORDS 


The last example procedure did not actually save the field values as a record to a file. To do this you 
need to use the APPEND command. This program, for example, allows you to add records to the 
example data file: 
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PROC count: 
LOCAL reply% 


OPEN “example”,A,f£%,f&,f£,£$ 





DO 
CLS 
AT 20,1 :PRINT “Record count=”; COUNT 
AT 9,5 :PRINT “(A)dd a record” 


AT 9,7 :PRINT “(Q) uit” 





reply%=GET 
IF replys=sq OR replys=%Q 


BREAK 








fo) 


ELSEIF replys=sA OR reply%s=%a 





add: 











ELSE 








B 





r. 


IEP 16,250 











ENDIF 
UNTIL 0 


ENDP 





PROC add: 


CLS 





Enter integer field:”; 


Enter long integer field:”; 

















‘lp 
als 
T 
EF 
PRINT “Enter numeric field:”; 
T 
T 
ae 

















INPUT A.f 
PRINT “Enter string field:”; 
INPUT A.f£S$ 
APPEND 
ENDP 
BEEP 


The BEEP command makes a beep of varying pitch and length: 





B 





Tr. 





EP duration%s,pitchs 


The duration is measured in '/;, of a second, so duration%=32 would give a beep a second long. Try 
pitch%=50 for a high beep, or 500 for a low beep. 





The number of records 


The COUNT function returns the number of records in the file. If you use it just after creating a 
database, it will return 0. As you add records the count increases. 
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How the values are saved 


Use the APPEND command to save a new record. This has no arguments. The values assigned to 
A.f£%,A.f£&,A.f andA.f$ are added as a new record to the end of the examp1e data file. If you 
only give values to some of the fields, not all, you won’t see any error message. If the fields happen to 
have values, these will be used; otherwise - null strings (“”) will be given to string fields, and zero to 
numeric fields. 


New field values are always added to the end of the current data file - as the last record in the file 
(if the file is a new one, it will also be the first record). 


At any time while a data file is open, the field names currently in use can be used like any other 
variable - for example, in a PRINT statement, or a string or numeric expression. 


APPEND and UPDATE 


APPEND adds the current field values to the end of the file as a new record, whereas UPDATE deletes 
the current record and adds the current field values to the end of the file as a new record. 


MoviNG FROM RECORD TO RECORD 


When you open or create a file, the first record in the file is current. To read, edit, or erase another 
record, you must make that record current - that is, move to it. Only one record is current at a time. To 
change the current record, use one of these commands: 


e POSITION ‘moves to’ a particular record, setting the field variables to the values in that record. 
For example, the instruction POSITION 3 makes record 3 the current record. The first record 
is record 1. 


e You can find the current record number by using the POS function, which returns the number of 
the current record. 


e FIRST moves to the first record in a file. 


e NEXT moves to the following record in a file. If the end of the file is passed, NEXT does not 
report an error, but the current record is a new, empty record. This case can be tested for with 
the EOF function. 


e BACK moves to the previous record in the file. If the current record is the first record in the file 
then that first record stays current. 


e LAST moves to the last record in the file. 


Deleting a record 
ERASE deletes the current record in the current file. 
The next record is then current. If the erased record was the last record in a file, then following this 


command the current record will be empty and EOF will return true. 


FINDING A RECORD 


FIND makes current the next record which has a field matching your search string. Capitals and 
lower-case letters match. For example: 


rS=FIND (“Brown”) 


would select the first record containing a string field with the value “Brown”, “brown” or “BROWN”, 
etc. The number of that record is returned, in this case to the variable r%. If the number returned is 
zero, no matching field was found. Any other number means that a match was found. 


The search includes the current record. So after finding a matching record, you need to use NEXT 
before you can continue searching through the following records. 


FIND (“Brown”) would not find a field “Mr Brown”. To find this, use wildcards, as explained below. 


40 


You can only search string fields, not number fields. For example, if you assigned the value 71 to 
the field a%, you could not find this with FIND. But if you assigned the value “71” to a$, you could 
find this. 


Wildcards 


r%=FIND (“*Brown*”) would make current the next record containing a string field in which 
Brown occurred - for example, the fields “MR BROWN”, “Brown A.R.” and “Browns Plumbing” 
would be matched. The wildcards you can use are: 


? matches any one character 
* matches any number of characters. 


Once you’ve found a matching record, you might display it on the screen, erase it or edit it. For 
example, to display all the records containing “BROWN”: 


FIRST 


WHILE FIND (“*BROWN*’) 








PRINT a.nameS,a.phone$ 


NEXT 





GET 


ENDWH 





More controlled finding 


FINDFIELD, like FIND, finds a string, makes the record with this string the current record, and returns 
the number of this record. However you can also use it to do case-dependent searching, to search 
backwards through the file, to search from the first record (forwards) or from the last record 
(backwards), and to search in one or more fields. 


£S=FINDFIELD (a$,start%,no%, flags) 





searches for the string a$ in no% fields in each record, starting at the field with number start% (1 is 
the number of the first field). start% and no% may refer to string fields only and other types will be 
ignored. The £l1ag% argument specifies the type of search as explained below. If you want to search in 
all fields, use 1 as the second argument and for the third argument use the number of fields you used in 
the OPEN/CREATE command. 


flag% should be specified as follows: 


search direction flag% 
backwards from current record 0 
forwards from current record 1 
backwards from end of file 2 
forwards from start of file 3 


aw 


I Constants for these flags are supplied in Const.oph. See the ‘Calling Procedures’ chapter for 
details of how to use this file and see Appendix E for a listing of it. 


Add 16 to the value of flag% given above to make the search case-dependent, where case-dependent 
means that the record will exactly match the search string in case as well as characters. Other wise the 
search will case-independent which means that upper case and lower case characters will match. 
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For example, if the following OPEN (or CREATE) statement had been used: 


OPEN “clients”,B,nm$,tel$,ad1$,ad2$,ad3$ 





then the command 





rS=FINDFIELD (“*Brown*”,1,3,16) 


will search the nm$, tel$ and ad1$ fields of each record for strings containing “Brown” searching 
case-dependently backwards from the current record. 


If you find a matching record and then you want to search again from this record, you must first use 
NEXT or BACK (according to the direction in which you are searching) to move past the record you 
have just found, otherwise the search will find the same match in the current record again. 


CHANGING/CLOSING THE CURRENT FILE 


Immediately after a file has been created or opened, it is automatically current. This means that the 
APPEND or UPDATE commands save records to this file, and the record-position commands 
(explained below) move around this file. You can still use the fields of other open files, for example 
A.field1=B.field2 


= 


USE makes current one of the other opened files. For example USE B selects the file with the logical 
name B (as specified in the OPEN or CREATE command which opened it). 





If you attempt to USE a file which has not yet been opened or created, an error is reported. 


In this procedure, the EOF function checks whether you are at the end of the current data file — that is, 
whether you’ve gone past the last record. You can use EOF in the test condition of a loop UNTIL EOF 
or WHILE NOT EOF in order to carry out a set of actions on all the records in a file. 


Example - copies selected records from one file to another 
PROC copyrec: 


OPEN “example”,A,f£%,f&,f£,£$ 











TRAP DELETE “temp” REM If file doesn’t exist, ignore error 

















CREATE “temp”,B,f£%,f&,f£,£$ 





PRINT “Copying EXAMPLE to TEMP” 























USE A REM the EXAMPLE file 











DO 
IF a.£%>30 and a.f<3.1415 
b.£%=a.£% 
b.f&=a.f& 
b.f=a.f 


b.f£S=“Selective copy” 



































USE B REM the TEMP file 
APPEND 
USE A 
ENDIF 
NEXT 
UNTIL EOF REM until End Of File 
CLOSE REM closes A; B becomes current 
CLOSE REM closes B 
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ENDP 





This example uses the DELETE command to delete any temp file which may exist, before making it 
afresh. Normally, if there were no temp file and you tried to delete it, an error would be generated. 
However, this example uses TRAP with the DELETE command. TRAP followed by a command means 
“fan error occurs in the command, carry on regardless”. The error value can then be found using ERR. 


There are more details of ERR and TRAP in the ‘Error Handling’ chapter. 


Closing a data file 


You should always ‘close’ a data file (with the CLOSE command) when you have finished using it. 
Data files close automatically when programs end. 


Tan 

I Youcan use up to 26 logical names (files or views — see the ‘Series 5 Data Handling’ chapter) at 
a time - if you are using 26 logical names and you want to use another one, you must close one of 
the open files or views first. CLOSE closes the file or view referred to by the current logical 
name. 


— 


You can only have 4 files open at a time - if you already have 4 files open and you want to access 
another one, you must close one of the open files first. CLOSE closes the current file. 


Keeping data files compressed 


When you change or delete records in a data file, the space taken by the old information is not 
automatically recovered. 


I By default, the space is not recovered when you close the file, unless you have used the 
SETFLAGS command to enable auto-compaction on closing a file. 


—_— 


By default, the space is recovered when you close the file, provided it is on ‘Internal drive’ or on 
a RAM SSD (i.e. it is not on a Flash SSD). 


Closing a very large file which contains changed or deleted records can be slow when compression is 
enabled, as the whole file beyond each old record needs copying down, each time. 


®: 
I Youcan prevent data file compression on the Series 3c if you wish, with these two lines: 





PpS=PEEKW (S1c)+S$le 

















POKEW p%,PEEKW(p%) or 1 











(Use any suitable integer variable for p%.) Files used by the current program will now not 
compress when they close. 


Use these two lines to re-enable auto-compression: 





PS=PEEKW (S1c)+S$le 

















POKEW p%, PEEKW(p%) and Sfffe 











Warning: be careful to enter these lines exactly as shown. These examples work by setting a 
system configuration flag. 


If you have closed a file without compression, you can recover the space by using the 
COMPRESS command to create a new, compressed version of the file. COMPRESS “dat” 
“new”, for example, creates a file called new which is a compressed version of dat, with the 
space which was taken up by old information now recovered. (You have to use COMPRESS to 
compress data files which are kept on a Flash SSD.) 





—> 


On the Series 5, you can use the COMPACT command when the database is closed. See the 
‘Series 5 Database Handling’ chapter. 
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SERIES 3c AND SIENA DATA FILES AND THE DATA APPLICATION 


The files you use with the Data application (listed under the Data icon in the System screen) often 
called databases or database files - are also just data files. 


Data files created by the Data application can be viewed in OPL, and vice versa. 


In OPL: to open a data file made by the Data application, begin its name with \DAT\, and end it with 
. DBF. For example, to open the file called data which the Data application normally uses: 





OPEN “\dat\data.dbf”,A,aS,b$,cS,d$... 
Restrictions: 


e You can use up to 32 field variables, all strings. It is possible for records to contain more than 32 
fields, but these fields cannot be accessed by OPL. It’s safe to change such a record and use 
UPDATE, though, as the extra fields will remain unchanged. 


e The maximum record length in OPL is 1022 characters. You will see a ‘Record too large’ error 
(-43) if your program tries to open a file which contains a record longer than this. 


e The Data application breaks up long records (over 255 characters) when storing them. They would 
appear as separate records to OPL. 


In the Data application: to examine an OPL data file, press the Data button, select ‘Open file’ from 
the ‘File’ menu and Control+Tab to type in a file name, and then type the name with \OPD\ on the 
front and . ODB at the end for example: 


\opd\example.odb 
Restrictions: 
e All of the fields must be string fields. 


e You can have up to a maximum of 32 fields, as specified in the CREATE command. If you view an 
OPL data file with the Data application, and add more lines to records than the number of fields 
specified in the original CREATE command, you will get an error if you subsequently try to access 
these additional fields in OPL. 


In both cases, you are using a more complete file specification. There is more about file specifications 
in the ‘Advanced Topics’ chapter. 


I For details of using Data application files in OPL on the Series 5, see the next chapter. 
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